<div class="tmd-doc">
<h1 class="tmd-header-1">
The Go Toolchain
</h1>
<p></p>
<div class="tmd-usual">
Currently, the tools in the official Go Toolchain (called Go Toolchain later) are the most used tools to develop Go projects. In Go 101 article series, all examples are compiled and verified with the standard Go compiler provided in Go Toolchain.
</div>
<p></p>
<div class="tmd-usual">
This article will introduce how to setup the Go development environment and how to use the <code class="tmd-code-span">go</code> command provided in Go Toolchain. Some other tools out of Go Toolchain will also be introduced.
</div>
<p></p>
<h3 class="tmd-header-3">
Install Go Toolchain
</h3>
<p></p>
<div class="tmd-usual">
Please <a href="https://go.dev/doc/install">download</a> Go Toolchain and install it by following the instructions shown in the download page.
</div>
<p></p>
<div class="tmd-usual">
We can also use the tool <a href="https://go101.org/apps-and-libs/gotv.html">GoTV</a> to manage installations of multiple Go toolchain versions and use them harmoniously and conveniently.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
The version of a Go Toolchain release is consistent with the highest Go language version the release supports. For example, Go Toolchain 1.25.x supports all Go language versions from 1.0 to Go 1.25.
</div>
<p></p>
<div class="tmd-usual">
The path to the <code class="tmd-code-span">bin</code> subfolder in Go Toolchain installation root path must be put in the <code class="tmd-code-span">PATH</code> environment variable to execute the tools (through the <code class="tmd-code-span">go</code> command) provided in Go Toolchain without inputting their full paths. If your Go Toolchain is installed through an installer or with a package manager, the path to the <code class="tmd-code-span">bin</code> subfolder may have been already set in the <code class="tmd-code-span">PATH</code> environment variable automatically for you.
</div>
<p></p>
<div class="tmd-usual">
The recent Go Toolchain versions support a feature called modules to manage project dependencies. The feature was introduced experimentally in version 1.11 and has been enabled by default since version 1.16.
</div>
<p></p>
<div class="tmd-usual">
There is an environment variable, <code class="tmd-code-span">GOPATH</code>, we should be aware of, though we don't need to care too much about it. It is defaulted to the path to the <code class="tmd-code-span">go</code> folder under the home directory of the current user. The <code class="tmd-code-span">GOPATH</code> environment variable may list multiple paths if it is specified manually. Later, when the <code class="tmd-code-span">GOPATH</code> folder is mentioned, it means the folder at the first path in the <code class="tmd-code-span">GOPATH</code> environment variable.
</div>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
The <code class="tmd-code-span">pkg</code> subfolder under the <code class="tmd-code-span">GOPATH</code> folder is used to store cached versions of Go modules (a Go module is a collection of Go packages) depended by local Go projects.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
There is a <code class="tmd-code-span">GOBIN</code> environment variable which controls where the Go program binary files generated by the <code class="tmd-code-span">go install</code> subcommand will be stored. The value of the <code class="tmd-code-span">GOBIN</code> environment variable is defaulted to the path to <code class="tmd-code-span">bin</code> subfolder under the <code class="tmd-code-span">GOPATH</code> folder. The <code class="tmd-code-span">GOBIN</code> path should be set in the <code class="tmd-code-span">PATH</code> environment variable if you would run the generated Go program binary files without specifying their full paths.
</div>
</li>
</ul>
<p></p>
<p></p>
<h3 class="tmd-header-3">
The Simplest Go Program
</h3>
<p></p>
<div class="tmd-usual">
Let's write a simple example and learn how to run simple Go programs.
</div>
<p></p>
<div class="tmd-usual">
The following program is the simplest Go program.
</div>
<pre class="tmd-code line-numbers must-line-numbers fixed-width">
<code class="language-go">package main

func main() {
}
</code></pre>
<p></p>
<div class="tmd-usual">
The words <code class="tmd-code-span">package</code> and <code class="tmd-code-span">func</code> are two keywords. The two <code class="tmd-code-span">main</code> words are two identifiers. Keywords and identifiers are introduced in <a href="keywords-and-identifiers.html">a coming article</a>.
</div>
<p></p>
<p></p>
<div class="tmd-usual">
The first line <code class="tmd-code-span">package main</code> specifies the package name (<code class="tmd-code-span">main</code> here) of the containing source file.
</div>
<p></p>
<div class="tmd-usual">
The second line is a blank line for better readability.
</div>
<p></p>
<div class="tmd-usual">
The remaining code declares a function which is also called <code class="tmd-code-span">main</code>. This <code class="tmd-code-span">main</code> function in a <code class="tmd-code-span">main</code> package specifies the entry point of a program. (Note that some other user code might be executed before the <code class="tmd-code-span">main</code> function gets invoked.)
</div>
<p></p>
<h3 class="tmd-header-3">
Run Go Programs
</h3>
<p></p>
<div class="tmd-usual">
Go Toolchain requires that Go source code file to have the extension <code class="tmd-code-span">.go</code>. Here, we assume the above source code is saved in a file named <code class="tmd-code-span">simplest-go-program.go</code>.
</div>
<p></p>
<div class="tmd-usual">
Open a terminal and change the current directory to the directory which contains the above source file, then run
</div>
<pre class="tmd-code output">
$ go run simplest-go-program.go
</pre>
<p></p>
<div class="tmd-usual">
Nothing is output? Yes, this program outputs nothing.
</div>
<p></p>
<div class="tmd-usual">
If there are some syntax errors in the source code, then these errors will be reported as compilation errors.
</div>
<p></p>
<div class="tmd-usual">
If multiple source files are in the <code class="tmd-code-span">main</code> package of a program, then we should run the program with the following command
</div>
<pre class="tmd-code output">
$ go run .
</pre>
<p></p>
<div class="tmd-usual">
Note,
</div>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
the <code class="tmd-code-span">go run</code> command is not recommended to compile and run large Go projects. It is just a convenient way to run simple Go programs, like the ones in the Go 101 articles. For large Go projects, please use the commands <code class="tmd-code-span">go build</code> or <code class="tmd-code-span">go install</code> to build then run executable binary files instead.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
each formal Go project supporting Go modules needs a <code class="tmd-code-span">go.mod</code> file located in the root folder of that project. The <code class="tmd-code-span">go.mod</code> file can be generated by the <code class="tmd-code-span">go mod init</code> subcommand (see below).
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
source files starting with <code class="tmd-code-span">_</code> or <code class="tmd-code-span">.</code> are ignored by Go Toolchain.
</div>
</li>
</ul>
<p></p>
<h3 class="tmd-header-3">
More <code class="tmd-code-span">go</code> Subcommands
</h3>
<p></p>
<div class="tmd-usual">
The three commands, <code class="tmd-code-span">go run</code>, <code class="tmd-code-span">go build</code> and <code class="tmd-code-span">go install</code>, only output code syntax errors (if any). They don't (try to) output code warnings (a.k.a., possible code logic mistakes). We can use the <code class="tmd-code-span">go vet</code> command to check and report such warnings.
</div>
<p></p>
<div class="tmd-usual">
We can (and should often) use the <code class="tmd-code-span">go fmt</code> command to format Go source code with a consistent coding style.
</div>
<p></p>
<div class="tmd-usual">
We can use the <code class="tmd-code-span">go test</code> command to run tests and benchmarks.
</div>
<p></p>
<div class="tmd-usual">
We can use the <code class="tmd-code-span">go doc</code> command to view Go documentation in terminal windows.
</div>
<p></p>
<div class="tmd-usual">
It is highly recommended to let your Go projects support the Go modules feature to ease dependency management. For projects supporting Go modules,
</div>
<ul class="tmd-list">
<li class="tmd-list-item">
<div class="tmd-usual">
the <code class="tmd-code-span">go mod init example.com/myproject</code> command is used to generate a <code class="tmd-code-span">go.mod</code> file in the current directory, which will be viewed as the root directory of a module called <code class="tmd-code-span">example.com/myproject</code>. The <code class="tmd-code-span">go.mod</code> file will be used to record module dependencies. We can edit the <code class="tmd-code-span">go.mod</code> file manually or let the <code class="tmd-code-span">go</code> subcommands to update it.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the <code class="tmd-code-span">go mod tidy</code> command is used to add missing module dependencies into and remove unused module dependencies from the <code class="tmd-code-span">go.mod</code> file by analyzing all the source code of the current project.
</div>
</li>
<li class="tmd-list-item">
<div class="tmd-usual">
the <code class="tmd-code-span">go get</code> command is used to add/upgrade/downgrade/remove a single dependency. This command is used less frequently than the <code class="tmd-code-span">go mod tidy</code> command.
</div>
</li>
</ul>
<p></p>
<div class="tmd-usual">
Since Go Toolchain 1.16, we can run <code class="tmd-code-span">go install example.com/program@latest</code> to install the latest version of a third-party Go program (into the <code class="tmd-code-span">GOBIN</code> folder). Before Go Toolchain 1.16, the corresponding command is <code class="tmd-code-span">go get -u example.com/program</code>, which has been deprecated now.
</div>
<p></p>
<div class="tmd-usual">
We can use the <code class="tmd-code-span">go help aSubCommand</code> command to view the help message for a specified sub command.
</div>
<p></p>
<div class="tmd-usual">
Run the <code class="tmd-code-span">go</code> command without any arguments to show the supported subcommands.
</div>
<p></p>
<div class="tmd-usual">
The Go 101 article series will not explain much more on how to use the tools provided in Go Toolchain. Please read the <a href="https://golang.org/cmd/go/">official documentation</a> for details.
</div>
<p></p>
<p></p>
<h3 id="doc" class="tmd-header-3">
View Go Package Docs in Browsers
</h3>
<p></p>
<div class="tmd-usual">
We could use the docs and source view tool <a href="https://github.com/go101/golds"><span class="tmd-bold">Golds</span></a> (<code class="tmd-code-span">go101.org/golds</code>) to locally view the docs of a specified Go project. This is not an official tool. It is developed by me (Tapir Liu). <span class="tmd-bold">Golds</span> supports rich code reading experiences (such as listing type implementation relations). After installing <span class="tmd-bold">Golds</span>, we can run <code class="tmd-code-span">golds std ./...</code> to view the docs of standard packages and packages in the current folder.
</div>
<p></p>
<div class="tmd-usual">
For official Go documentations, please visit <a href="https://go.dev">go.dev</a>.
</div>
<p></p>
<p></p>
</div>
